lang/php/lib/Schema/AvroArraySchema.php (1)

62-68: PHPDoc tag correction looks good, but return type union may be inconsistent.

The @returns → @return fix is correct. However, the declared return type AvroName|AvroSchema appears inconsistent with the actual implementation: the $items property (line 32) is typed as AvroSchema, and the method simply returns $this->items. The AvroName variant in the union type seems unreachable.

Consider whether the return type should be just AvroSchema, or if the property type needs updating to match the declared union.

lang/php/lib/IO/AvroStringIO.php (1)

82-84: Stale TODO comment references old naming convention.

The TODO comment on line 82 still mentions current_index but the property has been renamed to currentIndex.

📝 Proposed fix

     /**
-     * `@todo` test for fencepost errors wrt updating current_index
+     * `@todo` test for fencepost errors wrt updating currentIndex
      * `@param` mixed $len
      * `@return` string bytes read from buffer
      */

lang/php/lib/AvroDebug.php (1)

57-65: PHPDoc references old parameter name.

The docblock on line 58 still references $debug_level but the parameter has been renamed to $debugLevel.

📝 Proposed fix

     /**
-     * `@return` bool true if the given $debug_level is equivalent
+     * `@return` bool true if the given $debugLevel is equivalent
      *                  or more verbose than than the current debug level
      *                  and false otherwise.
      */

lang/php/lib/AvroGMP.php (3)

78-103: Missing explicit return type declaration.

The shiftLeft method has @return \GMP in its PHPDoc but lacks an explicit return type in the method signature. For consistency with the private helper methods (e.g., gmp_0xfs(): \GMP), consider adding the return type.

Also, line 79 has a typo: @interal should be @internal.

♻️ Proposed fix

     /**
-     * `@interal` Only works up to shift 63 (doesn't wrap bits around).
+     * `@internal` Only works up to shift 63 (doesn't wrap bits around).
      * `@param` int $shift number of bits to shift left
      * `@return` \GMP $g shifted left
      */
-    public static function shiftLeft(int|string|\GMP $g, int $shift)
+    public static function shiftLeft(int|string|\GMP $g, int $shift): \GMP

---

105-111: Missing explicit return type declaration.

The gmpTwosComplement method has @return \GMP in PHPDoc but lacks an explicit return type declaration for consistency.

♻️ Proposed fix

     /**
      * `@return` \GMP resource 64-bit two's complement of input.
      */
-    public static function gmpTwosComplement(int|string|\GMP $g)
+    public static function gmpTwosComplement(int|string|\GMP $g): \GMP

---

113-141: Missing explicit return type declaration.

The shiftRight method has @return \GMP in PHPDoc but lacks an explicit return type declaration for consistency.

♻️ Proposed fix

     /**
      * Arithmetic right shift
      * `@param` int $shift number of bits to shift right
      * `@return` \GMP $g shifted right $shift bits
      */
-    public static function shiftRight(int|string|\GMP $g, int $shift)
+    public static function shiftRight(int|string|\GMP $g, int $shift): \GMP

lang/php/lib/DataFile/AvroDataIOReader.php (2)

94-94: Use strict comparison for consistency.

Line 94 uses loose comparison (==) while other codec checks in this file use strict comparison (===). For consistency and to avoid type coercion issues, use strict comparison here as well.

Proposed fix

-            if (0 == $this->blockCount) {
+            if (0 === $this->blockCount) {

---

274-291: Potential issue with unpack() return value.

unpack() can return false on failure. While unlikely with controlled input, accessing [1] without validating the return could cause an error.

Defensive fix

     private function snappyUncompress(string $compressed): string
     {
         if (!extension_loaded('snappy')) {
             throw new AvroException('Please install ext-snappy to use snappy compression.');
         }
-        $crc32 = unpack('N', substr((string) $compressed, -4))[1];
+        $unpacked = unpack('N', substr($compressed, -4));
+        if (false === $unpacked) {
+            throw new AvroException('snappy uncompression failed - could not read CRC32.');
+        }
+        $crc32 = $unpacked[1];
-        $datum = snappy_uncompress(substr((string) $compressed, 0, -4));
+        $datum = snappy_uncompress(substr($compressed, 0, -4));
 
         if (false === $datum) {
             throw new AvroException('snappy uncompression failed.');
         }
 
         if ($crc32 !== crc32($datum)) {
             throw new AvroException('snappy uncompression failed - crc32 mismatch.');
         }
 
         return $datum;
     }

Note: The (string) casts on lines 279-280 are redundant since $compressed is already typed as string.

lang/php/lib/Schema/AvroRecordSchema.php (1)

152-167: Consider memoization for fieldsByAlias().

Unlike fieldsHash() which memoizes the result, fieldsByAlias() rebuilds the hash on every call. If this method is called frequently, consider applying the same memoization pattern.

Proposed memoization pattern

+    /**
+     * `@var` null|array<string, AvroField> map of field aliases to field objects.
+     */
+    private ?array $fieldsByAliasHash = null;
+
     /**
      * `@return` array<string, AvroField>
      */
     public function fieldsByAlias(): array
     {
+        if (is_null($this->fieldsByAliasHash)) {
             $hash = [];
             foreach ($this->fields as $field) {
                 if ($field->hasAliases()) {
                     foreach ($field->getAliases() as $a) {
                         $hash[$a] = $field;
                     }
                 }
             }
+            $this->fieldsByAliasHash = $hash;
+        }
 
-        return $hash;
+        return $this->fieldsByAliasHash;
     }

lang/php/lib/Datum/AvroIODatumWriter.php (3)

143-159: Inconsistent parameter naming.

The writeBytes method still uses $writers_schema (snake_case) while other methods use $writersSchema (camelCase). Update for consistency with the rest of the file.

Proposed fix

-    private function writeBytes(AvroSchema $writers_schema, string $datum, AvroIOBinaryEncoder $encoder): void
+    private function writeBytes(AvroSchema $writersSchema, string $datum, AvroIOBinaryEncoder $encoder): void
     {
-        $logicalType = $writers_schema->logicalType();
+        $logicalType = $writersSchema->logicalType();

---

178-193: Incomplete camelCase rename in writeMap.

The local variable $datum_count on line 184 should be renamed to $datumCount for consistency with the camelCase refactoring in this PR.

Proposed fix

     private function writeMap(AvroMapSchema $writersSchema, array $datum, AvroIOBinaryEncoder $encoder): void
     {
-        $datum_count = count($datum);
-        if ($datum_count > 0) {
-            $encoder->writeLong($datum_count);
+        $datumCount = count($datum);
+        if ($datumCount > 0) {
+            $encoder->writeLong($datumCount);

---

252-271: Incomplete camelCase rename in writeUnion.

The local variables $datum_schema_index and $datum_schema on lines 254-255 should be renamed to camelCase for consistency.

Proposed fix

     private function writeUnion(AvroUnionSchema $writersSchema, mixed $datum, AvroIOBinaryEncoder $encoder): void
     {
-        $datum_schema_index = -1;
-        $datum_schema = null;
+        $datumSchemaIndex = -1;
+        $datumSchema = null;
         foreach ($writersSchema->schemas() as $index => $schema) {
             if (AvroSchema::isValidDatum($schema, $datum)) {
-                $datum_schema_index = $index;
-                $datum_schema = $schema;
+                $datumSchemaIndex = $index;
+                $datumSchema = $schema;
 
                 break;
             }
         }
 
-        if (is_null($datum_schema)) {
+        if (is_null($datumSchema)) {
             throw new AvroIOTypeException($writersSchema, $datum);
         }
 
-        $encoder->writeLong($datum_schema_index);
-        $this->writeValidatedData($datum_schema, $datum, $encoder);
+        $encoder->writeLong($datumSchemaIndex);
+        $this->writeValidatedData($datumSchema, $datum, $encoder);
     }

lang/php/lib/DataFile/AvroDataIO.php (2)

132-165: Inconsistent parameter naming in openFile.

The parameter $file_path uses snake_case while other parameters use camelCase ($schemaJson). Consider renaming to $filePath for consistency.

Proposed fix

     public static function openFile(
-        string $file_path,
+        string $filePath,
         string $mode = AvroIO::READ_MODE,
         ?string $schemaJson = null,
         string $codec = self::NULL_CODEC
     ): AvroDataIOReader|AvroDataIOWriter {

---

170-173: Simplify null check in isValidCodec.

Since $codec is typed as ?string, the is_string($codec) check is essentially a null check. Consider using !is_null($codec) or simply $codec !== null for clarity.

Proposed fix

     public static function isValidCodec(?string $codec): bool
     {
-        return is_string($codec) && in_array($codec, self::validCodecs());
+        return null !== $codec && in_array($codec, self::validCodecs(), true);
     }

Note: Also added true as the third parameter to in_array for strict comparison.

lang/php/lib/Datum/AvroIOBinaryDecoder.php (2)

161-164: Minor: Remove empty line in skipNull.

The empty line in the method body is unnecessary.

Proposed fix

     public function skipNull(): void
     {
-
     }

---

218-221: Consider suppressing unused parameter warning.

The $writersSchema parameter in skipEnum is unused but likely kept for API consistency with other skip methods. Add a PHPDoc annotation to suppress the warning and document the intent.

Proposed fix

+    /**
+     * `@param` AvroSchema $writersSchema kept for API consistency with other skip methods
+     * `@SuppressWarnings`(PHPMD.UnusedFormalParameter)
+     */
     public function skipEnum(AvroSchema $writersSchema, AvroIOBinaryDecoder $decoder): void
     {
         $decoder->skipInt();
     }